home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / clipper / ks94an.zip / __REIDX.HDR < prev    next >
Text File  |  1994-04-25  |  16KB  |  374 lines
  1. /******************************************************************************
  2.                  The Klipper Library, for CA-Clipper 5.x
  3.         Copyright (c), 1994, Wallace Information Systems Engineering
  4.  
  5. FUNCTION:
  6.  
  7. _ReIndex( acFileName ) --> NIL
  8.  
  9. PARAMETERS:
  10.  
  11. cFileName : (Optional) array of databases to reindex. (Default = ALL dbfs)
  12.  
  13. SHORT:
  14.  
  15. Reindex databases according to index specifications on file.
  16.  
  17. DESCRIPTION:
  18.  
  19. _ReIndex() uses the DATALINK.DAT file to create index files for the databases
  20. listed therein.
  21.  
  22. The structure of the DATALINK.DAT file should be:
  23.  
  24. FILE_NAME,  C, 8
  25. FILE_EXT,   C, 3
  26. OWNER_NAME, C, 8
  27. OWNER_EXT,  C, 3
  28. OWNERALIAS, C, 15
  29. INDEX_KEY,  C, 75
  30. FILE_DESC,  C, 75
  31. LAST_NTXD,  D
  32. LAST_NTXT,  C, 8
  33. USE_COUNT,  N, 12
  34. PACK,       L
  35. MEMOPACK,   L
  36. INCLUDE,    L
  37. MAX_RECS,   N, 10
  38. MAX_RFILE,  C, 12
  39. MAX_DATE,   D
  40. MAX_DAYS,   N, 8
  41. DATE_FIELD, C, 10
  42. MAX_DFILE,  C, 12
  43. FLAG,       C, 1
  44.  
  45. This file is created on the first call to _ReIndex() or to _SetIndex() if the
  46. file does not exists.  It is created empty and therefore needs to be filled
  47. in with data concerning the files that you wish to have indexed.
  48.  
  49. Indexing Sub-System
  50.  
  51. OVERVIEW
  52.  
  53. The Index Sub-System provides a mechanism for automating the indexing,
  54. packing, memo file condensing, and rudimentary record archiving of
  55. application databases [the _ReIndex() function]; and, an index file
  56. management function that automates the opening of indexes for application
  57. databases [the _SetIndex() function].
  58.  
  59. Both of these functions use an Index Control File that contains data that
  60. describes the databases, indexes, and other information.  (The default name
  61. of this file is MENUDEF.DAT, however, the calling application may change this
  62. name to any other valid file name.  See Technical Details.)  Each record in
  63. this Table identifies either 1) an index that is to be associated with a
  64. particular database, or 2) a database file that is to be processed in some
  65. form during reindexing.
  66.  
  67. The _ReIndex() function is called typically as a stand-alone procedure.
  68. Ordinarily, it will be called directly from a menu item while there are no
  69. databases open (including other users in a network environment).  The nature
  70. of a complete database index is such that the files must be opened
  71. exclusively, and that is what _ReIndex() does.  Any database file that
  72. _ReIndex() cannot open in EXCLUSIVE mode is skipped and not reindexed, or
  73. processed in any way.
  74.  
  75. When _ReIndex() begins processing, it processes each file named in the Index
  76. Control File in the physical order that they appear, according to the various
  77. options that are defined in each record.  (See Technical Details for indepth
  78. description.)  Some may be requests to build indexes, others may be requests
  79. to perform any of the various archiving functions, or a combination of both.
  80.  
  81. _SetIndex(), uses the same Index Control File, but for a different purpose.
  82. _SetIndex() is used to open indexes for a database.  When _SetIndex() is
  83. called, it refers to the Index Control File to gather information on all
  84. indexes that are related to the database specified.  It then opens ALL
  85. indexes associated with that database.  The primary advantage is that the
  86. programmer is spared the burden of remembering to open all indexes that have
  87. been created for any given database, the system tracks these details.  When
  88. you call _SetIndex(), you are assured that all index files for the specified
  89. database will be opened and updated as edits are made.  In addition to
  90. opening multiple index files, the _SetIndex() function can be told to make
  91. one of those indexes the primary (or controlling) index.
  92.  
  93. TECHNICAL DETAILS
  94.  
  95. _ReIndex() Function
  96.  
  97. The database administration is data driven by means of an Index Control File.
  98.  The structure of this file is as follows:
  99.  
  100. FILE_NAME,  C, 8
  101. FILE_EXT,   C, 3
  102. OWNER_NAME, C, 8
  103. OWNER_EXT,  C, 3
  104. OWNERALIAS, C, 15
  105. INDEX_KEY,  C, 75
  106. FILE_DESC,  C, 75
  107. LAST_NTXD,  D
  108. LAST_NTXT,  C, 8
  109. USE_COUNT,  N, 12
  110. PACK,       L
  111. MEMOPACK,   L
  112. INCLUDE,    L
  113. MAX_RECS,   N, 10
  114. MAX_RFILE,  C, 12
  115. MAX_DATE,   D
  116. MAX_DAYS,   N, 8
  117. DATE_FIELD, C, 10
  118. MAX_DFILE,  C, 12
  119. FLAG,       C, 1
  120.  
  121. The following is an explanation of these fields.
  122.  
  123. FILE_NAME: The FILE name of the INDEX FILE.
  124.  
  125. FILE_EXT: The file name EXTENSION of the INDEX FILE.
  126.  
  127. OWNER_NAME: The FILE name of the corresponding DATABASE.
  128.  
  129. OWNER_EXT: The file name EXTENSION of the DATABASE.
  130.  
  131. OWNERALIAS: The ALIAS name to be used when opening the file for indexing.
  132. (Aliases affect the index key if specified in the index key expression, thus
  133. this may be necessary if you include alias information in the index key
  134. itself.)
  135.  
  136. INDEX_KEY: This is any valid Clipper Index Expression on which to build the
  137. index.
  138.  
  139. FILE_DESC: This is a text field that can be used to describe the index file
  140. and it's purpose.  It is optional and is not used by the Index Sub-System in
  141. any way.
  142.  
  143. LAST_NTXD: This field is maintained by the Index Sub-System and contains the
  144. DATE() that the index was last built.
  145.  
  146. LAST_NTXT: This field is maintained by the Index Sub-System and contains the
  147. TIME() that the index was last built.
  148.  
  149. USE_COUNT: This field is maintained by the Index Sub-System and keeps a
  150. running count of the number of times that the index has been used by the
  151. indexing routines (_ReIndex()) and by the _SetIndex() function.
  152.  
  153. PACK: This is a logical field.  If it contains a logical TRUE, then this
  154. database file is PACKED when the Index Sub-System rebuilds indexes.  If it
  155. contains a logical FALSE, this file is NOT packed.  Note that if you have
  156. requested any of the record archive features, the file will also be packed,
  157. even if PACK is FALSE.
  158.  
  159. MEMOPACK: This is a logical field.  If it contains a logical TRUE, then this
  160. database's MEMO FILE (.DBT) is PACKED when the Index Sub-System rebuilds
  161. indexes.  If it contains a logical FALSE, this file's memo file is NOT
  162. packed.  If the specified database has no memo field(s), then MEMOPACK is not
  163. executed, even if requested.
  164.  
  165. Memo Files allocate disk storage in 512K blocks.  When a particular memo
  166. field overflows this 512K block, the entire block is copied to a new block at
  167. the end of the file, and more space is allocated.  The original block is then
  168. marked as being unused, but remains a part of the .DBT file.  (More detailed
  169. information can be found in the Clipper 5.0 Reference Manual).  For this
  170. reason, memo fields tend to grow exponentially.  Specifying TRUE in this
  171. field causes the memo file to be rewritten, eliminating unused blocks.
  172.  
  173. INCLUDE: This is a logical field.  If it contains a logical TRUE, then this
  174. database file is included for processing when the Index Sub-System rebuilds
  175. indexes.  If it contains a logical FALSE, this file is NOT packed.
  176.  
  177. If a file is INCLUDED, all actions specified for that file are accomplished.
  178. This includes indexing, packing, memopacking, record archiving, etc.  If
  179. INCLUDE contains a logical FALSE, no processing of any type is performed.
  180.  
  181. The following six fields are responsible for record archiving and deletion
  182. based upon three criteria: Age, Date, and Number of Records on File.
  183.  
  184. There are three ways to automatically remove records from the database files
  185. referenced in the Index Control File.  The first way is to specify a maximum
  186. number of records that the file can contain before the excess records are
  187. deleted.  The second and third ways are similar, but operate on slightly
  188. different principles.  You specify a date field in the database to be used in
  189. a comparison AND EITHER a date before which records will be deleted, OR a
  190. maximum number of days old a record can be before it is deleted.  This is not
  191. a rigid either/or situation, you can specify both.  In fact, you can specify
  192. all three criteria for a single database along with the index key for
  193. indexing all in one Index Control File record.
  194.  
  195. MAX_RECS:  This numeric field, if not zero, is used to remove records based
  196. upon how many records are in the database file.  For instance, if this field
  197. contains 100, then only the LAST 100 records will remain in the file.  All
  198. records other than the last 100 are deleted.
  199.  
  200. Notice that specifying a non-zero number in this field causes the database to
  201. be PACKED regardless of whether the PACK field is TRUE or FALSE.
  202.  
  203. MAX_RFILE: This character field can contain a file name.  If it is a valid
  204. file name, records that are deleted based upon MAX_RECS are copied to this
  205. file BEFORE being deleted from the application database file.  This makes it
  206. possible to MOVE records from the database file to an archive file.
  207.  
  208. MAX_DATE:  This date field works in conjunction with the application database
  209. field specified in the DATE_FIELD field to remove records based upon a date
  210. comparison.  If a non-blank date is entered here, then only those records
  211. whose DATE_FIELD field is greater than MAX_DATE remain.  All others are
  212. deleted.
  213.  
  214. MAX_DAYS:  This numeric field works in conjunction with the application
  215. database field specified in the DATE_FIELD field to remove records based upon
  216. a date comparison.  If a non-zero number is entered here, then only records
  217. that are less than MAX_DAYS number of days from the date in the DATE_FIELD
  218. field remain.  All others are deleted.
  219.  
  220. DATE_FIELD:  This is the date field in the application database that is used
  221. for comparisons against MAX_DATE and MAX_DAYS.
  222.  
  223. MAX_DFILE:  This character field contains a file name into which are move
  224. records that are deleted by the MAX_DAYS and MAX_DATE functions.  If this
  225. field is empty, records deleted by date comparisons are simply deleted. If
  226. this field contains a valid file name, then those records deleted by the date
  227. comparisons are copied here BEFORE being deleted.  This makes it possible to
  228. create an archive file of records that are moved out of the application
  229. database based upon a cutoff date or age.
  230.  
  231. Index Status Report
  232.  
  233. The database Index Control File is used to rebuild all indexes and perform
  234. record archiving whenever your application makes a call to _ReIndex().  When
  235. this call is made, a prompt is presented asking whether or not to print a
  236. status report.  This prompt overlays the application screen and restores the
  237. screen to it's previous state once the question has been answered.
  238.  
  239. Screen Activity during Processing
  240.  
  241. During processing, a box is presented that informs you of the progress of the
  242. processing.  As each record in the Index Control File is encountered, the
  243. status box is updated to reflect which file is currently being processed and,
  244. as options are encountered, they are presented also:
  245.  
  246. PACK: The database is currently being packed
  247.  
  248. MEMOPACK: The database memo fields are being condensed.
  249.  
  250. NO MEMOS: A MEMOPACK was requested on the current database, but the file has
  251. no memo fields. The MEMOPACK request is ignored, and this information message
  252. is displayed for appx one second.
  253.  
  254. ARCHIVE-R: The database is being processed to remove records based upon
  255. Maximum Records Criteria.
  256.  
  257. ARCHIVE-D1: The database is being processed to remove records based upon a
  258. Date Cutoff Criteria.
  259.  
  260. ARCHIVE-D2: The database is being processed to remove records based upon a
  261. Date Age Criteria.
  262.  
  263. _SetIndex() Function
  264.  
  265. The _SetIndex() function uses the same Index Control File to locate and open
  266. application database indexes.  However, it is makes reference only to the
  267. following fields:
  268.  
  269. OWNER_NAME/OWNER_EXT: These fields are compared against the specified
  270. application database name to determine whether the index contained in
  271. FILE_NAME/FILE_EXT are to be opened for the current application database.
  272.  
  273. If the index is determined to belong to the specified application database,
  274. then the index is opened, and the USE_COUNT field for this OWNER_NAME is
  275. incremented by one. This information field can be used to determine the
  276. frequency of use for the various application databases and indexes.  Note
  277. that this field is incremented each time the INDEX specified in FILE_NAME is
  278. opened by _SetIndex() and each time the DATABASE specified in the OWNER_NAME
  279. field is opened.
  280.  
  281. Calling Convention and Parameters
  282.  
  283. IMPORTANT NOTE:  The Index Sub-System should be called when all databases are
  284. closed.  Typically, you should have a menu option called, "Database
  285. Indexing", or something similar from which the indexing Sub-System function
  286. is called.  Indexing requires EXCLUSIVE use of each of the databases.
  287.  
  288. Syntax:
  289.  
  290. _ReIndex([acOwner])
  291.  
  292. The function takes one optional parameter.  If you do not wish to reindex ALL
  293. databases specified in the Index Control File, you may optionally pass, as a
  294. parameter, a character array containing one file name per element that you
  295. wish to include in this pass.  Example:
  296.  
  297. LOCAL aFiles1 := { 'BUDGET.DBF' }
  298. LOCAL aFiles2 := { 'BUDGET.DBF','FORECAST.DBF' }
  299.  
  300. _ReIndex()
  301. _ReIndex(aFiles1)
  302. _ReIndex(aFiles2)
  303.  
  304. In the first call, all databases in the Index Control File will be processed.
  305.  
  306. In the second call, only BUDGET.DBF will be processed.  In the final example,
  307. both BUDGET.DBF and FORECAST.DBF will be processed.
  308.  
  309. Syntax:
  310.  
  311. _SetIndex( cTableName [,cInitControl] )
  312.  
  313. The function takes two parameters, the second is optional. The first
  314. parameter is the name of the application database that you wish to open
  315. indexes for.  There may be up to 15 indexes per database file.  If no
  316. associated index information is found in the Index Control File, then no
  317. indexes are opened.
  318.  
  319. As the Index Control File is scanned, index information is gathered in the
  320. order that they occur in the file.  The Index Control File is itself ordered
  321. by OWNER_NAME, but inside that, physical record order is the only order.
  322. Therefore, the index files will be listed in the order that they were
  323. entered.  Once all of the index files have been identified for a given
  324. database, _SetIndex() then attempts to decide which of the indexes should be
  325. made the controlling index.  In other words, which order will it SET ORDER
  326. TO...?
  327.  
  328. If the cInitControl parameter is NOT passed, _SetIndex() will attempt to make
  329. the index that has the same FILE_NAME as OWNER_NAME.  If BUDGET.DBF is the
  330. name of the database, and three indexes for BUDGET.DBF are specified:
  331.  
  332. _SetIndex('BUDGET.DBF')
  333.  
  334. BUDGT91.NTX
  335. BUDGET.NTX
  336. BUDGT90.NTX
  337.  
  338. then the controlling index will be BUDGET.NTX because it has the same file
  339. name as the database file.
  340.  
  341. The second, optional parameter, cInitControl is used to give controlling
  342. order to one of the indexes.  For instance, in the above example, if you
  343. explicitly wanted to make BUDGT91.NTX the controlling index, your function
  344. call would have been:
  345.  
  346. _SetIndex('BUDGET.DBF','BUDGT91.NTX')
  347.  
  348. If you specifically name a controlling index in cInitControl parameter, and
  349. that file does not exist in the Index Control File (even if the file exists
  350. on the disk), then the program will terminate with a programmed Run-Time
  351. Error Message.  The reason for this is that because the cInitControl argument
  352. is optional, if you specify it, and do not know that it doesn't exist in the
  353. Index Control File, then you are asking for an Abnormal Termination and
  354. Run-Time error shortly thereafter, or worse, erratic behavior from the
  355. system.  If you specify a controlling index, you MUST make certain that it
  356. exists in the Index Control File.
  357.  
  358. NOTE:
  359.  
  360.  
  361.  
  362. EXAMPLE:
  363.  
  364. _ReIndex()
  365.  
  366. Result: All files specified in DATALINK.DAT are indexed
  367.  
  368. _ReIndex({'MAIN.DBF'})
  369.  
  370. Result: All indexes specified for MAIN.DBF in the DATALINK.DAT file are
  371. built.
  372.  
  373. ******************************************************************************/
  374.